From ff61948d1393c7500ecbea4b03c87c744ce371b7 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Tadej=20Borov=C5=A1ak?= Date: Thu, 13 May 2010 04:51:37 +0200 Subject: [PATCH] Move documentation to inline comments: GdkWindow MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Use examples/gdk to store documentation code examples. Fixes https://bugzilla.gnome.org/show_bug.cgi?id=618498 Signed-off-by: Javier Jardón --- docs/reference/gdk/tmpl/.gitignore | 1 + docs/reference/gdk/tmpl/windows.sgml | 1771 ---------------------- examples/gdk/composited-window-example.c | 136 ++ gdk/gdkevents.h | 32 + gdk/gdktypes.h | 55 + gdk/gdkwindow.c | 63 + gdk/gdkwindow.h | 306 +++- gdk/x11/gdkdnd-x11.c | 6 + gdk/x11/gdkwindow-x11.c | 6 +- 9 files changed, 566 insertions(+), 1810 deletions(-) create mode 100644 docs/reference/gdk/tmpl/.gitignore delete mode 100644 docs/reference/gdk/tmpl/windows.sgml create mode 100644 examples/gdk/composited-window-example.c diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore new file mode 100644 index 0000000000..888b6a26b9 --- /dev/null +++ b/docs/reference/gdk/tmpl/.gitignore @@ -0,0 +1 @@ +windows.sgml diff --git a/docs/reference/gdk/tmpl/windows.sgml b/docs/reference/gdk/tmpl/windows.sgml deleted file mode 100644 index c2e725ed34..0000000000 --- a/docs/reference/gdk/tmpl/windows.sgml +++ /dev/null @@ -1,1771 +0,0 @@ - -Windows - - -Onscreen display areas in the target window system - - - -A #GdkWindow is a rectangular region on the screen. It's a low-level object, -used to implement high-level objects such as #GtkWidget and #GtkWindow on the -GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think of -as a "window" with a titlebar and so on; a #GtkWindow may contain many #GdkWindow. -For example, each #GtkButton has a #GdkWindow associated with it. - -Composited Windows - -Normally, the windowing system takes care of rendering the contents of a child -window onto its parent window. This mechanism can be intercepted by calling -gdk_window_set_composited() on the child window. For a -composited window it is the responsibility of the -application to render the window contents at the right spot. - -Composited windows - - -/* The expose event handler for the event box. - * - * This function simply draws a transparency onto a widget on the area - * for which it receives expose events. This is intended to give the - * event box a "transparent" background. - * - * In order for this to work properly, the widget must have an RGBA - * colourmap. The widget should also be set as app-paintable since it - * doesn't make sense for GTK+ to draw a background if we are drawing it - * (and because GTK+ might actually replace our transparency with its - * default background colour). - */ -static gboolean -transparent_expose (GtkWidget *widget, - GdkEventExpose *event) -{ - cairo_t *cr; - - cr = gdk_cairo_create (widget->window); - cairo_set_operator (cr, CAIRO_OPERATOR_CLEAR); - gdk_cairo_region (cr, event->region); - cairo_fill (cr); - cairo_destroy (cr); - - return FALSE; -} - -/* The expose event handler for the window. - * - * This function performs the actual compositing of the event box onto - * the already-existing background of the window at 50% normal opacity. - * - * In this case we do not want app-paintable to be set on the widget - * since we want it to draw its own (red) background. Because of this, - * however, we must ensure that we use g_signal_connect_after so that - * this handler is called after the red has been drawn. If it was - * called before then GTK would just blindly paint over our work. - * - * Note: if the child window has children, then you need a cairo 1.6 - * feature to make this work correctly. - */ -static gboolean -window_expose_event (GtkWidget *widget, - GdkEventExpose *event) -{ - GdkRegion *region; - GtkWidget *child; - cairo_t *cr; - - /* get our child (in this case, the event box) */ - child = gtk_bin_get_child (GTK_BIN (widget)); - - /* create a cairo context to draw to the window */ - cr = gdk_cairo_create (widget->window); - - /* the source data is the (composited) event box */ - gdk_cairo_set_source_pixmap (cr, child->window, - child->allocation.x, - child->allocation.y); - - /* draw no more than our expose event intersects our child */ - region = gdk_region_rectangle (&child->allocation); - gdk_region_intersect (region, event->region); - gdk_cairo_region (cr, region); - cairo_clip (cr); - - /* composite, with a 50% opacity */ - cairo_set_operator (cr, CAIRO_OPERATOR_OVER); - cairo_paint_with_alpha (cr, 0.5); - - /* we're done */ - cairo_destroy (cr); - - return FALSE; -} - -int -main (int argc, char **argv) -{ - GtkWidget *window, *event, *button; - GdkScreen *screen; - GdkColormap *rgba; - GdkColor red; - - gtk_init (&argc, &argv); - - /* Make the widgets */ - button = gtk_button_new_with_label ("A Button"); - event = gtk_event_box_new (); - window = gtk_window_new (GTK_WINDOW_TOPLEVEL); - - /* Put a red background on the window */ - gdk_color_parse ("red", &red); - gtk_widget_modify_bg (window, GTK_STATE_NORMAL, &red); - - /* Set the colourmap for the event box. - * Must be done before the event box is realised. - */ - screen = gtk_widget_get_screen (event); - rgba = gdk_screen_get_rgba_colormap (screen); - gtk_widget_set_colormap (event, rgba); - - /* Set our event box to have a fully-transparent background - * drawn on it. Currently there is no way to simply tell GTK+ - * that "transparency" is the background colour for a widget. - */ - gtk_widget_set_app_paintable (GTK_WIDGET (event), TRUE); - g_signal_connect (event, "expose-event", - G_CALLBACK (transparent_expose), NULL); - - /* Put them inside one another */ - gtk_container_set_border_width (GTK_CONTAINER (window), 10); - gtk_container_add (GTK_CONTAINER (window), event); - gtk_container_add (GTK_CONTAINER (event), button); - - /* Realise and show everything */ - gtk_widget_show_all (window); - - /* Set the event box GdkWindow to be composited. - * Obviously must be performed after event box is realised. - */ - gdk_window_set_composited (event->window, TRUE); - - /* Set up the compositing handler. - * Note that we do _after_ so that the normal (red) background is drawn - * by gtk before our compositing occurs. - */ - g_signal_connect_after (window, "expose-event", - G_CALLBACK (window_expose_event), NULL); - - gtk_main (); - - return 0; -} -]]> - - -In the example , a button is -placed inside of an event box inside of a window. The event box is -set as composited and therefore is no longer automatically drawn to -the screen. - - -When the contents of the event box change, an expose event is -generated on its parent window (which, in this case, belongs to -the toplevel #GtkWindow). The expose handler for this widget is -responsible for merging the changes back on the screen in the way -that it wishes. - - -In our case, we merge the contents with a 50% transparency. We -also set the background colour of the window to red. The effect is -that the background shows through the button. - - -Offscreen Windows - -Offscreen windows are more general than composited windows, since they -allow not only to modify the rendering of the child window onto its parent, -but also to apply coordinate transformations. - - -To integrate an offscreen window into a window hierarchy, one has to call -gdk_offscreen_window_set_embedder() and handle a number of signals. The -#GdkWindow::pick-embedded-child signal on the embedder window is used to -select an offscreen child at given coordinates, and the #GdkWindow::to-embedder -and #GdkWindow::from-embedder signals on the offscreen window are used to -translate coordinates between the embedder and the offscreen window. - - - -For rendering an offscreen window onto its embedder, the contents of the -offscreen window are available as a pixmap, via -gdk_offscreen_window_get_pixmap(). - - - - - - - - - - - - - - - - -An opaque structure representing an onscreen drawable. -Pointers to structures of type #GdkPixmap, #GdkBitmap, -and #GdkWindow, can often be used interchangeably. -The type #GdkDrawable refers generically to any of -these types. - - - - - - - - -@gdkwindow: the object which received the signal. -@arg1: -@arg2: -@arg3: -@arg4: - - - - - - -@gdkwindow: the object which received the signal. -@arg1: -@arg2: -@Returns: - - - - - - -@gdkwindow: the object which received the signal. -@arg1: -@arg2: -@arg3: -@arg4: - - - - - - - - -Describes the kind of window. - - -@GDK_WINDOW_ROOT: root window; this window has no parent, covers the entire screen, and is created by the window system -@GDK_WINDOW_TOPLEVEL: toplevel window (used to implement #GtkWindow) -@GDK_WINDOW_CHILD: child window (used to implement e.g. #GtkEntry) -@GDK_WINDOW_DIALOG: useless/deprecated compatibility type -@GDK_WINDOW_TEMP: override redirect temporary window (used to implement #GtkMenu) -@GDK_WINDOW_FOREIGN: foreign window (see gdk_window_foreign_new()) -@GDK_WINDOW_OFFSCREEN: offscreen window (see ). Since 2.18 - - - -@GDK_INPUT_OUTPUT windows are the standard kind of window you might expect. -@GDK_INPUT_ONLY windows are invisible; they are used to trap events, but -you can't draw on them. - - -@GDK_INPUT_OUTPUT: window for graphics and events -@GDK_INPUT_ONLY: window for events only - - - -Used to indicate which fields of a #GdkGeometry struct should be paid attention -to. Also, the presence/absence of @GDK_HINT_POS, @GDK_HINT_USER_POS, and -@GDK_HINT_USER_SIZE is significant, though they don't directly refer to -#GdkGeometry fields. @GDK_HINT_USER_POS will be set automatically by #GtkWindow -if you call gtk_window_move(). @GDK_HINT_USER_POS and @GDK_HINT_USER_SIZE -should be set if the user specified a size/position using a --geometry -command-line argument; gtk_window_parse_geometry() automatically sets these -flags. - - -@GDK_HINT_POS: indicates that the program has positioned the window -@GDK_HINT_MIN_SIZE: min size fields are set -@GDK_HINT_MAX_SIZE: max size fields are set -@GDK_HINT_BASE_SIZE: base size fields are set -@GDK_HINT_ASPECT: aspect ratio fields are set -@GDK_HINT_RESIZE_INC: resize increment fields are set -@GDK_HINT_WIN_GRAVITY: window gravity field is set -@GDK_HINT_USER_POS: indicates that the window's position was explicitly set by the user -@GDK_HINT_USER_SIZE: indicates that the window's size was explicitly set by the user - - - -The #GdkGeometry struct gives the window manager information about -a window's geometry constraints. Normally you would set these on -the GTK+ level using gtk_window_set_geometry_hints(). #GtkWindow -then sets the hints on the #GdkWindow it creates. - - - -gdk_window_set_geometry_hints() expects the hints to be fully valid already and -simply passes them to the window manager; in contrast, -gtk_window_set_geometry_hints() performs some interpretation. For example, -#GtkWindow will apply the hints to the geometry widget instead of the toplevel -window, if you set a geometry widget. Also, the -@min_width/@min_height/@max_width/@max_height fields may be set to -1, and -#GtkWindow will substitute the size request of the window or geometry widget. If -the minimum size hint is not provided, #GtkWindow will use its requisition as -the minimum size. If the minimum size is provided and a geometry widget is set, -#GtkWindow will take the minimum size as the minimum size of the geometry widget -rather than the entire window. The base size is treated similarly. - - - -The canonical use-case for gtk_window_set_geometry_hints() is to get a terminal -widget to resize properly. Here, the terminal text area should be the geometry -widget; #GtkWindow will then automatically set the base size to the size of -other widgets in the terminal window, such as the menubar and scrollbar. Then, -the @width_inc and @height_inc fields should be set to the size of one character -in the terminal. Finally, the base size should be set to the size of one -character. The net effect is that the minimum size of the terminal -will have a 1x1 character terminal area, and only terminal sizes on -the "character grid" will be allowed. - - - -Here's an example of how the terminal example would be implemented, assuming -a terminal area widget called "terminal" and a toplevel window "toplevel": - - GdkGeometry hints; - - hints.base_width = terminal->char_width; - hints.base_height = terminal->char_height; - hints.min_width = terminal->char_width; - hints.min_height = terminal->char_height; - hints.width_inc = terminal->char_width; - hints.height_inc = terminal->char_height; - - gtk_window_set_geometry_hints (GTK_WINDOW (toplevel), - GTK_WIDGET (terminal), - &hints, - GDK_HINT_RESIZE_INC | - GDK_HINT_MIN_SIZE | - GDK_HINT_BASE_SIZE); - - - - -The other useful fields are the @min_aspect and @max_aspect fields; these -contain a width/height ratio as a floating point number. If a geometry widget is -set, the aspect applies to the geometry widget rather than the entire window. -The most common use of these hints is probably to set @min_aspect and -@max_aspect to the same value, thus forcing the window to keep a constant aspect -ratio. - - -@min_width: minimum width of window (or -1 to use requisition, with #GtkWindow only) -@min_height: minimum height of window (or -1 to use requisition, with #GtkWindow only) -@max_width: maximum width of window (or -1 to use requisition, with #GtkWindow only) -@max_height: maximum height of window (or -1 to use requisition, with #GtkWindow only) -@base_width: allowed window widths are @base_width + @width_inc * N where N is any integer (-1 allowed with #GtkWindow) -@base_height: allowed window widths are @base_height + @height_inc * N where N is any integer (-1 allowed with #GtkWindow) -@width_inc: width resize increment -@height_inc: height resize increment -@min_aspect: minimum width/height ratio -@max_aspect: maximum width/height ratio -@win_gravity: window gravity, see gtk_window_set_gravity() - - - -Defines the reference point of a window and the meaning of coordinates -passed to gtk_window_move(). See gtk_window_move() and the "implementation -notes" section of the -Extended -Window Manager Hints specification for more details. - - -@GDK_GRAVITY_NORTH_WEST: the reference point is at the top left corner. -@GDK_GRAVITY_NORTH: the reference point is in the middle of the top edge. -@GDK_GRAVITY_NORTH_EAST: the reference point is at the top right corner. -@GDK_GRAVITY_WEST: the reference point is at the middle of the left edge. -@GDK_GRAVITY_CENTER: the reference point is at the center of the window. -@GDK_GRAVITY_EAST: the reference point is at the middle of the right edge. -@GDK_GRAVITY_SOUTH_WEST: the reference point is at the lower left corner. -@GDK_GRAVITY_SOUTH: the reference point is at the middle of the lower edge. -@GDK_GRAVITY_SOUTH_EAST: the reference point is at the lower right corner. -@GDK_GRAVITY_STATIC: the reference point is at the top left corner of the - window itself, ignoring window manager decorations. - - - -Determines a window edge or corner. - - -@GDK_WINDOW_EDGE_NORTH_WEST: the top left corner. -@GDK_WINDOW_EDGE_NORTH: the top edge. -@GDK_WINDOW_EDGE_NORTH_EAST: the top right corner. -@GDK_WINDOW_EDGE_WEST: the left edge. -@GDK_WINDOW_EDGE_EAST: the right edge. -@GDK_WINDOW_EDGE_SOUTH_WEST: the lower left corner. -@GDK_WINDOW_EDGE_SOUTH: the lower edge. -@GDK_WINDOW_EDGE_SOUTH_EAST: the lower right corner. - - - -These are hints for the window manager that indicate what type of function -the window has. The window manager can use this when determining decoration -and behaviour of the window. The hint must be set before mapping the window. - - -See the -Extended -Window Manager Hints specification for more details about -window types. - - -@GDK_WINDOW_TYPE_HINT_NORMAL: Normal toplevel window. -@GDK_WINDOW_TYPE_HINT_DIALOG: Dialog window. -@GDK_WINDOW_TYPE_HINT_MENU: Window used to implement a menu; GTK+ uses - this hint only for torn-off menus, see #GtkTearoffMenuItem. -@GDK_WINDOW_TYPE_HINT_TOOLBAR: Window used to implement toolbars. -@GDK_WINDOW_TYPE_HINT_SPLASHSCREEN: Window used to display a splash - screen during application startup. -@GDK_WINDOW_TYPE_HINT_UTILITY: Utility windows which are not detached - toolbars or dialogs. -@GDK_WINDOW_TYPE_HINT_DOCK: Used for creating dock or panel windows. -@GDK_WINDOW_TYPE_HINT_DESKTOP: Used for creating the desktop background -window. -@GDK_WINDOW_TYPE_HINT_DROPDOWN_MENU: A menu that belongs to a menubar. -@GDK_WINDOW_TYPE_HINT_POPUP_MENU: A menu that does not belong to a menubar, - e.g. a context menu. -@GDK_WINDOW_TYPE_HINT_TOOLTIP: A tooltip. -@GDK_WINDOW_TYPE_HINT_NOTIFICATION: A notification - typically a "bubble" - that belongs to a status icon. -@GDK_WINDOW_TYPE_HINT_COMBO: A popup from a combo box. -@GDK_WINDOW_TYPE_HINT_DND: A window that is used to implement a DND cursor. - - - -Attributes to use for a newly-created window. - - -@title: title of the window (for toplevel windows) -@event_mask: event mask (see gdk_window_set_events()) -@x: X coordinate relative to parent window (see gdk_window_move()) -@y: Y coordinate relative to parent window (see gdk_window_move()) -@width: width of window -@height: height of window -@wclass: #GDK_INPUT_OUTPUT (normal window) or #GDK_INPUT_ONLY (invisible window that receives events) -@visual: #GdkVisual for window -@colormap: #GdkColormap for window -@window_type: type of window -@cursor: cursor for the window (see gdk_window_set_cursor()) -@wmclass_name: don't use (see gtk_window_set_wmclass()) -@wmclass_class: don't use (see gtk_window_set_wmclass()) -@override_redirect: %TRUE to bypass the window manager -@type_hint: a hint of the function of the window - - - -Used to indicate which fields in the #GdkWindowAttr struct should be -honored. For example, if you filled in the "cursor" and "x" fields of -#GdkWindowAttr, pass "@GDK_WA_X | @GDK_WA_CURSOR" to gdk_window_new(). Fields -in #GdkWindowAttr not covered by a bit in this enum are required; for example, -the @width/@height, @wclass, and @window_type fields are required, they have no -corresponding flag in #GdkWindowAttributesType. - - -@GDK_WA_TITLE: Honor the title field -@GDK_WA_X: Honor the X coordinate field -@GDK_WA_Y: Honor the Y coordinate field -@GDK_WA_CURSOR: Honor the cursor field -@GDK_WA_COLORMAP: Honor the colormap field -@GDK_WA_VISUAL: Honor the visual field -@GDK_WA_WMCLASS: Honor the wmclass_class and wmclass_name fields -@GDK_WA_NOREDIR: Honor the override_redirect field -@GDK_WA_TYPE_HINT: Honor the type_hint field - - - - - - -@parent: -@attributes: -@attributes_mask: -@Returns: - - - - - - - -@window: - - - - - - - -@window: -@Returns: - - - - - - - -@win_x: -@win_y: -@Returns: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@Returns: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: -@setting: - - - - - - - -@window: -@setting: - - - - - - - -@window: -@opacity: - - - - - - - -@window: -@composited: - - - - - - - -@window: -@x: -@y: - - - - - - - -@window: -@width: -@height: - - - - - - - -@window: -@x: -@y: -@width: -@height: - - - - - - - -@window: -@dx: -@dy: - - - - - - - -@window: -@region: -@dx: -@dy: - - - - - - - -@window: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@new_parent: -@x: -@y: - - - - - - - -@window: - - - - - - - -@window: -@x: -@y: -@width: -@height: - - - - - - - -@window: -@x: -@y: -@width: -@height: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: -@sibling: -@above: - - - - - - - -@window: -@timestamp: - - - - -Registers a window as a potential drop destination. - - -@window: a #GdkWindow. - - - - - - - -@window: -@edge: -@button: -@root_x: -@root_y: -@timestamp: - - - - - - - -@window: -@button: -@root_x: -@root_y: -@timestamp: - - - - - - - -@geometry: -@flags: -@width: -@height: -@new_width: -@new_height: - - - - - - - -@window: - - - - - - - -@window: -@rectangle: - - - - - - - -@window: -@region: - - - - - - - -@window: - - - - - - - -@window: -@rect: -@invalidate_children: - - - - - - - -@window: -@region: -@invalidate_children: - - - - - - - -@window: -@region: -@GdkWindow *, gpointer: -@GdkWindow *, gpointer: -@user_data: - - - - - - - -@window: -@Returns: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@void: - - - - - - - -@window: -@update_children: - - - - - - - -@setting: - - - - - - - -@window: -@real_drawable: -@x_offset: -@y_offset: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: -@user_data: - - - - - - - -@window: -@override_redirect: - - - - - - - -@window: -@accept_focus: - - - - - - - -@window: -@focus_on_map: - - - - - - - -@window: -@function: -@data: - - - - - - - -@window: -@function: -@data: - - - - -Specifies the type of function used to filter native events before they are -converted to GDK events. - - - -When a filter is called, @event is unpopulated, except for -event->window. The filter may translate the native -event to a GDK event and store the result in @event, or handle it without -translation. If the filter translates the event and processing should -continue, it should return GDK_FILTER_TRANSLATE. - - -@xevent: the native event to filter. -@event: the GDK event to which the X event will be translated. -@data: user data set when the filter was installed. -@Returns: a #GdkFilterReturn value. - - - - -Specifies the result of applying a #GdkFilterFunc to a native event. - - -@GDK_FILTER_CONTINUE: event not handled, continue processing. -@GDK_FILTER_TRANSLATE: native event translated into a GDK event and stored - in the event structure that was passed in. -@GDK_FILTER_REMOVE: event handled, terminate processing. - - - -Used to represent native events (XEvents for the X11 -backend, MSGs for Win32). - - - - - - - - -@window: -@mask: -@x: -@y: - - - - - - - -@window: -@shape_region: -@offset_x: -@offset_y: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: -@mask: -@x: -@y: - - - - - - - -@window: -@shape_region: -@offset_x: -@offset_y: - - - - - - - -@window: - - - - - - - -@window: - - - - - - - -@window: -@use_static: -@Returns: - - - - - - - -@window: -@title: - - - - - - - -@window: -@color: - - - - - - - -@window: -@pixmap: -@parent_relative: - - - - -A special value for GdkPixmap* variables, indicating -that the background pixmap for a window should be inherited from the parent -window. - - - - - - - - - -@window: -@cursor: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@data: - - - - - - - -@window: -@x: -@y: -@width: -@height: -@depth: - - - - - - - -@window: -@geometry: -@geom_mask: - - - - - - - -@window: -@pixbufs: - - - - - - - -@window: -@modal: - - - - - - - -@window: -@hint: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@skips_taskbar: - - - - - - - -@window: -@skips_pager: - - - - - - - -@window: -@urgent: - - - - - - - -@window: -@x: -@y: - - - - - - - -@window: -@x: -@y: - - - - - - - -@window: -@rect: - - - - - - - -@window: -@x: -@y: -@Returns: - - - - - - - -@window: -@x: -@y: -@Returns: - - - - - - - -@window: -@x: -@y: -@root_x: -@root_y: - - - - - - - -@window: -@x: -@y: -@mask: -@Returns: - - - - -A set of bit-flags to indicate the state of modifier keys and mouse buttons -in various event types. Typical modifier keys are Shift, Control, Meta, Super, -Hyper, Alt, Compose, Apple, CapsLock or ShiftLock. - - -Like the X Window System, GDK supports 8 modifier keys and 5 mouse buttons. - - -Since 2.10, GDK recognizes which of the Meta, Super or Hyper keys are mapped -to Mod2 - Mod5, and indicates this by setting %GDK_SUPER_MASK, %GDK_HYPER_MASK -or %GDK_META_MASK in the state field of key events. - - -@GDK_SHIFT_MASK: the Shift key. -@GDK_LOCK_MASK: a Lock key (depending on the modifier mapping of the - X server this may either be CapsLock or ShiftLock). -@GDK_CONTROL_MASK: the Control key. -@GDK_MOD1_MASK: the fourth modifier key (it depends on the modifier - mapping of the X server which key is interpreted as this modifier, but - normally it is the Alt key). -@GDK_MOD2_MASK: the fifth modifier key (it depends on the modifier - mapping of the X server which key is interpreted as this modifier). -@GDK_MOD3_MASK: the sixth modifier key (it depends on the modifier - mapping of the X server which key is interpreted as this modifier). -@GDK_MOD4_MASK: the seventh modifier key (it depends on the modifier - mapping of the X server which key is interpreted as this modifier). -@GDK_MOD5_MASK: the eighth modifier key (it depends on the modifier - mapping of the X server which key is interpreted as this modifier). -@GDK_BUTTON1_MASK: the first mouse button. -@GDK_BUTTON2_MASK: the second mouse button. -@GDK_BUTTON3_MASK: the third mouse button. -@GDK_BUTTON4_MASK: the fourth mouse button. -@GDK_BUTTON5_MASK: the fifth mouse button. -@GDK_SUPER_MASK: the Super modifier. Since 2.10 -@GDK_HYPER_MASK: the Hyper modifier. Since 2.10 -@GDK_META_MASK: the Meta modifier. Since 2.10 -@GDK_RELEASE_MASK: not used in GDK itself. GTK+ uses it to differentiate - between (keyval, modifiers) pairs from key press and release events. -@GDK_MODIFIER_MASK: a mask covering all modifier types. - - - - - - -@window: -@Returns: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@event_mask: - - - - - - - -@window: -@icon_window: -@pixmap: -@mask: - - - - - - - -@window: -@name: - - - - - - - -@window: -@parent: - - - - - - - -@window: -@role: - - - - - - - -@window: -@startup_id: - - - - - - - -@window: -@leader: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@decorations: - - - - - - - -@window: The window to get the decorations from -@decorations: The window decorations will be written here -@Returns: %TRUE if the window has decorations set, %FALSE otherwise. - - - - -These are hints originally defined by the Motif toolkit. -The window manager can use them when determining how to decorate -the window. The hint must be set before mapping the window. - - -@GDK_DECOR_ALL: all decorations should be applied. -@GDK_DECOR_BORDER: a frame should be drawn around the window. -@GDK_DECOR_RESIZEH: the frame should have resize handles. -@GDK_DECOR_TITLE: a titlebar should be placed above the window. -@GDK_DECOR_MENU: a button for opening a menu should be included. -@GDK_DECOR_MINIMIZE: a minimize button should be included. -@GDK_DECOR_MAXIMIZE: a maximize button should be included. - - - - - - -@window: -@functions: - - - - -These are hints originally defined by the Motif toolkit. -The window manager can use them when determining the functions -to offer for the window. -The hint must be set before mapping the window. - - -@GDK_FUNC_ALL: all functions should be offered. -@GDK_FUNC_RESIZE: the window should be resizable. -@GDK_FUNC_MOVE: the window should be movable. -@GDK_FUNC_MINIMIZE: the window should be minimizable. -@GDK_FUNC_MAXIMIZE: the window should be maximizable. -@GDK_FUNC_CLOSE: the window should be closable. - - - - - - -@void: -@Returns: - - - - - - - -@void: -@Returns: - - - - -A table of pointers to functions for getting quantities related to -the current pointer position. GDK has one global table of this type, -which can be set using gdk_set_pointer_hooks(). - - -This is only useful for such low-level tools as an event recorder. -Applications should never have any reason to use this facility - - -@get_pointer: Obtains the current pointer position and modifier state. - The position is given in coordinates relative to the window containing - the pointer, which is returned in @window. -@window_at_pointer: Obtains the window underneath the mouse pointer, - returning the location of that window in @win_x, @win_y. Returns %NULL - if the window under the mouse pointer is not known to GDK (for example, - belongs to another application). - - - - - - -@new_hooks: -@Returns: - - - - - - - -@window: -@Returns: - - - - - - - -@window: -@embedder: - - - - - - - -@window: -@Returns: - - - - - - - -@window: - - - - - - - -@window: -@drawable: -@src_x: -@src_y: -@dest_x: -@dest_y: -@width: -@height: - - - - - - - -@window: - - - - - diff --git a/examples/gdk/composited-window-example.c b/examples/gdk/composited-window-example.c new file mode 100644 index 0000000000..b28f712a2e --- /dev/null +++ b/examples/gdk/composited-window-example.c @@ -0,0 +1,136 @@ +#include + +/* The expose event handler for the event box. + * + * This function simply draws a transparency onto a widget on the area + * for which it receives expose events. This is intended to give the + * event box a "transparent" background. + * + * In order for this to work properly, the widget must have an RGBA + * colourmap. The widget should also be set as app-paintable since it + * doesn't make sense for GTK+ to draw a background if we are drawing it + * (and because GTK+ might actually replace our transparency with its + * default background colour). + */ +static gboolean +transparent_expose (GtkWidget *widget, + GdkEventExpose *event) +{ + cairo_t *cr; + + cr = gdk_cairo_create (widget->window); + cairo_set_operator (cr, CAIRO_OPERATOR_CLEAR); + gdk_cairo_region (cr, event->region); + cairo_fill (cr); + cairo_destroy (cr); + + return FALSE; + } + +/* The expose event handler for the window. + * + * This function performs the actual compositing of the event box onto + * the already-existing background of the window at 50% normal opacity. + * + * In this case we do not want app-paintable to be set on the widget + * since we want it to draw its own (red) background. Because of this, + * however, we must ensure that we use g_signal_connect_after so that + * this handler is called after the red has been drawn. If it was + * called before then GTK would just blindly paint over our work. + * + * Note: if the child window has children, then you need a cairo 1.6 + * feature to make this work correctly. + */ +static gboolean +window_expose_event (GtkWidget *widget, + GdkEventExpose *event) +{ + GdkRegion *region; + GtkWidget *child; + cairo_t *cr; + + /* get our child (in this case, the event box) */ + child = gtk_bin_get_child (GTK_BIN (widget)); + + /* create a cairo context to draw to the window */ + cr = gdk_cairo_create (widget->window); + + /* the source data is the (composited) event box */ + gdk_cairo_set_source_pixmap (cr, child->window, + child->allocation.x, + child->allocation.y); + + /* draw no more than our expose event intersects our child */ + region = gdk_region_rectangle (&child->allocation); + gdk_region_intersect (region, event->region); + gdk_cairo_region (cr, region); + cairo_clip (cr); + + /* composite, with a 50% opacity */ + cairo_set_operator (cr, CAIRO_OPERATOR_OVER); + cairo_paint_with_alpha (cr, 0.5); + + /* we're done */ + cairo_destroy (cr); + + return FALSE; +} + +int +main (int argc, char **argv) +{ + GtkWidget *window, *event, *button; + GdkScreen *screen; + GdkColormap *rgba; + GdkColor red; + + gtk_init (&argc, &argv); + + /* Make the widgets */ + button = gtk_button_new_with_label ("A Button"); + event = gtk_event_box_new (); + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + + /* Put a red background on the window */ + gdk_color_parse ("red", &red); + gtk_widget_modify_bg (window, GTK_STATE_NORMAL, &red); + + /* Set the colourmap for the event box. + * Must be done before the event box is realised. + */ + screen = gtk_widget_get_screen (event); + rgba = gdk_screen_get_rgba_colormap (screen); + gtk_widget_set_colormap (event, rgba); + + /* Set our event box to have a fully-transparent background + * drawn on it. Currently there is no way to simply tell GTK+ + * that "transparency" is the background colour for a widget. + */ + gtk_widget_set_app_paintable (GTK_WIDGET (event), TRUE); + g_signal_connect (event, "expose-event", + G_CALLBACK (transparent_expose), NULL); + + /* Put them inside one another */ + gtk_container_set_border_width (GTK_CONTAINER (window), 10); + gtk_container_add (GTK_CONTAINER (window), event); + gtk_container_add (GTK_CONTAINER (event), button); + + /* Realise and show everything */ + gtk_widget_show_all (window); + + /* Set the event box GdkWindow to be composited. + * Obviously must be performed after event box is realised. + */ + gdk_window_set_composited (event->window, TRUE); + + /* Set up the compositing handler. + * Note that we do _after_ so that the normal (red) background is drawn + * by gtk before our compositing occurs. + */ + g_signal_connect_after (window, "expose-event", + G_CALLBACK (window_expose_event), NULL); + + gtk_main (); + + return 0; +} diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h index 72b9e4246a..2f7a09b8d5 100644 --- a/gdk/gdkevents.h +++ b/gdk/gdkevents.h @@ -72,10 +72,25 @@ typedef void (*GdkEventFunc) (GdkEvent *event, /* Event filtering */ +/** + * GdkXEvent: + * + * Used to represent native events (XEvents for the X11 + * backend, MSGs for Win32). + */ typedef void GdkXEvent; /* Can be cast to window system specific * even type, XEvent on X11, MSG on Win32. */ +/** + * GdkFilterReturn: + * @GDK_FILTER_CONTINUE: event not handled, continue processing. + * @GDK_FILTER_TRANSLATE: native event translated into a GDK event and stored + * in the event structure that was passed in. + * @GDK_FILTER_REMOVE: event handled, terminate processing. + * + * Specifies the result of applying a #GdkFilterFunc to a native event. + */ typedef enum { GDK_FILTER_CONTINUE, /* Event not handled, continue processesing */ GDK_FILTER_TRANSLATE, /* Native event translated into a GDK event and @@ -84,6 +99,23 @@ typedef enum { GDK_FILTER_REMOVE /* Terminate processing, removing event */ } GdkFilterReturn; +/** + * GdkFilterFunc: + * @xevent: the native event to filter. + * @event: the GDK event to which the X event will be translated. + * @data: user data set when the filter was installed. + * + * Specifies the type of function used to filter native events before they are + * converted to GDK events. + * + * When a filter is called, @event is unpopulated, except for + * event->window. The filter may translate the native + * event to a GDK event and store the result in @event, or handle it without + * translation. If the filter translates the event and processing should + * continue, it should return %GDK_FILTER_TRANSLATE. + * + * Returns: a #GdkFilterReturn value. + */ typedef GdkFilterReturn (*GdkFilterFunc) (GdkXEvent *xevent, GdkEvent *event, gpointer data); diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h index ae9362f70f..78748dc3d3 100644 --- a/gdk/gdktypes.h +++ b/gdk/gdktypes.h @@ -56,6 +56,13 @@ /* some common magic values */ #define GDK_CURRENT_TIME 0L + +/** + * GDK_PARENT_RELATIVE: + * + * A special value for #GdkPixmap variables, indicating that the background + * pixmap for a window should be inherited from the parent window. + */ #define GDK_PARENT_RELATIVE 1L @@ -111,6 +118,15 @@ typedef struct _GdkVisual GdkVisual; typedef struct _GdkDrawable GdkDrawable; typedef struct _GdkDrawable GdkBitmap; typedef struct _GdkDrawable GdkPixmap; + +/** + * GdkWindow: + * + * An opaque structure representing an onscreen drawable. Pointers to structures + * of type #GdkPixmap, #GdkBitmap, and #GdkWindow can often be used + * interchangeably. The type #GdkDrawable refers generically to any of these + * types. + */ typedef struct _GdkDrawable GdkWindow; typedef struct _GdkDisplay GdkDisplay; typedef struct _GdkScreen GdkScreen; @@ -123,6 +139,45 @@ typedef enum /* Types of modifiers. */ +/** + * GdkModifierType: + * @GDK_SHIFT_MASK: the Shift key. + * @GDK_LOCK_MASK: a Lock key (depending on the modifier mapping of the + * X server this may either be CapsLock or ShiftLock). + * @GDK_CONTROL_MASK: the Control key. + * @GDK_MOD1_MASK: the fourth modifier key (it depends on the modifier + * mapping of the X server which key is interpreted as this modifier, but + * normally it is the Alt key). + * @GDK_MOD2_MASK: the fifth modifier key (it depends on the modifier + * mapping of the X server which key is interpreted as this modifier). + * @GDK_MOD3_MASK: the sixth modifier key (it depends on the modifier + * mapping of the X server which key is interpreted as this modifier). + * @GDK_MOD4_MASK: the seventh modifier key (it depends on the modifier + * mapping of the X server which key is interpreted as this modifier). + * @GDK_MOD5_MASK: the eighth modifier key (it depends on the modifier + * mapping of the X server which key is interpreted as this modifier). + * @GDK_BUTTON1_MASK: the first mouse button. + * @GDK_BUTTON2_MASK: the second mouse button. + * @GDK_BUTTON3_MASK: the third mouse button. + * @GDK_BUTTON4_MASK: the fourth mouse button. + * @GDK_BUTTON5_MASK: the fifth mouse button. + * @GDK_SUPER_MASK: the Super modifier. Since 2.10 + * @GDK_HYPER_MASK: the Hyper modifier. Since 2.10 + * @GDK_META_MASK: the Meta modifier. Since 2.10 + * @GDK_RELEASE_MASK: not used in GDK itself. GTK+ uses it to differentiate + * between (keyval, modifiers) pairs from key press and release events. + * @GDK_MODIFIER_MASK: a mask covering all modifier types. + * + * A set of bit-flags to indicate the state of modifier keys and mouse buttons + * in various event types. Typical modifier keys are Shift, Control, Meta, + * Super, Hyper, Alt, Compose, Apple, CapsLock or ShiftLock. + * + * Like the X Window System, GDK supports 8 modifier keys and 5 mouse buttons. + * + * Since 2.10, GDK recognizes which of the Meta, Super or Hyper keys are mapped + * to Mod2 - Mod5, and indicates this by setting %GDK_SUPER_MASK, + * %GDK_HYPER_MASK or %GDK_META_MASK in the state field of key events. + */ typedef enum { GDK_SHIFT_MASK = 1 << 0, diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c index e264feb86c..d4895ebfe0 100644 --- a/gdk/gdkwindow.c +++ b/gdk/gdkwindow.c @@ -25,6 +25,69 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +/** + * SECTION:windows + * @Short_description: Onscreen display areas in the target window system + * @Title: Windows + * + * A #GdkWindow is a rectangular region on the screen. It's a low-level object, + * used to implement high-level objects such as #GtkWidget and #GtkWindow on the + * GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think + * of as a "window" with a titlebar and so on; a #GtkWindow may contain many + * #GdkWindows. For example, each #GtkButton has a #GdkWindow associated + * with it. + * + * + * Composited Windows + * + * Normally, the windowing system takes care of rendering the contents of a + * child window onto its parent window. This mechanism can be intercepted by + * calling gdk_window_set_composited() on the child window. For a + * composited window it is the responsibility of the + * application to render the window contents at the right spot. + * + * + * Composited windows + * + * FIXME: MISSING XINCLUDE CONTENT + * + * + * In the example , a button is + * placed inside of an event box inside of a window. The event box is set as + * composited and therefore is no longer automatically drawn to the screen. + * + * When the contents of the event box change, an expose event is generated on + * it's parent window (which, in this case, belongs to the toplevel #GtkWindow). + * The expose handler for this widget is responsible for merging the changes + * back on the screen in the way that it wishes. + * + * In our case, we merge the contents with a 50% transparency. We also set the + * background colour of the window to red. The effect is that the background + * shows through the button. + * + * + * + * Offscreen Windows + * + * Offscreen windows are more general than composited windows, since they allow + * not only to modify the rendering of the child window onto its parent, but + * also to apply coordinate transformations. + * + * To integrate an offscreen window into a window hierarchy, one has to call + * gdk_offscreen_window_set_embedder() and handle a number of signals. The + * #GdkWindow::pick-embedded-child signal on the embedder window is used to + * select an offscreen child at given coordinates, and the + * #GdkWindow::to-embedder and #GdkWindow::from-embedder signals on the + * offscreen window are used to translate coordinates between the embedder and + * the offscreen window. + * + * For rendering an offscreen window onto its embedder, the contents of the + * offscreen window are available as a pixmap, via + * gdk_offscreen_window_get_pixmap(). + * + * + */ + #include "config.h" #include "gdkwindow.h" #include "gdkwindowimpl.h" diff --git a/gdk/gdkwindow.h b/gdk/gdkwindow.h index 5d2ade8168..ee3c89ee20 100644 --- a/gdk/gdkwindow.h +++ b/gdk/gdkwindow.h @@ -42,14 +42,16 @@ typedef struct _GdkWindowAttr GdkWindowAttr; typedef struct _GdkPointerHooks GdkPointerHooks; typedef struct _GdkWindowRedirect GdkWindowRedirect; -/* Classes of windows. - * InputOutput: Almost every window should be of this type. Such windows - * receive events and are also displayed on screen. - * InputOnly: Used only in special circumstances when events need to be - * stolen from another window or windows. Input only windows - * have no visible output, so they are handy for placing over - * top of a group of windows in order to grab the events (or - * filter the events) from those windows. +/** + * GdkWindowClass: + * @GDK_INPUT_OUTPUT: window for graphics and events + * @GDK_INPUT_ONLY: window for events only + * + * @GDK_INPUT_OUTPUT windows are the standard kind of window you might expect. + * Such windows receive events and are also displayed on screen. + * @GDK_INPUT_ONLY windows are invisible; they are usually placed above other + * windows in order to trap or filter the events. You can't draw on + * @GDK_INPUT_ONLY windows. */ typedef enum { @@ -57,18 +59,20 @@ typedef enum GDK_INPUT_ONLY } GdkWindowClass; -/* Types of windows. - * Root: There is only 1 root window and it is initialized - * at startup. Creating a window of type GDK_WINDOW_ROOT - * is an error. - * Toplevel: Windows which interact with the window manager. - * Child: Windows which are children of some other type of window. - * (Any other type of window). Most windows are child windows. - * Dialog: A special kind of toplevel window which interacts with - * the window manager slightly differently than a regular - * toplevel window. Dialog windows should be used for any - * transient window. - * Foreign: A window that actually belongs to another application +/** + * GdkWindowType: + * @GDK_WINDOW_ROOT: root window; this window has no parent, covers the entire + * screen, and is created by the window system + * @GDK_WINDOW_TOPLEVEL: toplevel window (used to implement #GtkWindow) + * @GDK_WINDOW_CHILD: child window (used to implement e.g. #GtkEntry) + * @GDK_WINDOW_DIALOG: useless/deprecated compatibility type + * @GDK_WINDOW_TEMP: override redirect temporary window (used to implement + * #GtkMenu) + * @GDK_WINDOW_FOREIGN: foreign window (see gdk_window_foreign_new()) + * @GDK_WINDOW_OFFSCREEN: offscreen window (see + * ). Since 2.18 + * + * Describes the kind of window. */ typedef enum { @@ -81,13 +85,24 @@ typedef enum GDK_WINDOW_OFFSCREEN } GdkWindowType; -/* Window attribute mask values. - * GDK_WA_TITLE: The "title" field is valid. - * GDK_WA_X: The "x" field is valid. - * GDK_WA_Y: The "y" field is valid. - * GDK_WA_CURSOR: The "cursor" field is valid. - * GDK_WA_COLORMAP: The "colormap" field is valid. - * GDK_WA_VISUAL: The "visual" field is valid. +/** + * GdkWindowAttributesType: + * @GDK_WA_TITLE: Honor the title field + * @GDK_WA_X: Honor the X coordinate field + * @GDK_WA_Y: Honor the Y coordinate field + * @GDK_WA_CURSOR: Honor the cursor field + * @GDK_WA_COLORMAP: Honor the colormap field + * @GDK_WA_VISUAL: Honor the visual field + * @GDK_WA_WMCLASS: Honor the wmclass_class and wmclass_name fields + * @GDK_WA_NOREDIR: Honor the override_redirect field + * @GDK_WA_TYPE_HINT: Honor the type_hint field + * + * Used to indicate which fields in the #GdkWindowAttr struct should be honored. + * For example, if you filled in the "cursor" and "x" fields of #GdkWindowAttr, + * pass "@GDK_WA_X | @GDK_WA_CURSOR" to gdk_window_new(). Fields in + * #GdkWindowAttr not covered by a bit in this enum are required; for example, + * the @width/@height, @wclass, and @window_type fields are required, they have + * no corresponding flag in #GdkWindowAttributesType. */ typedef enum { @@ -104,6 +119,29 @@ typedef enum /* Size restriction enumeration. */ +/** + * GdkWindowHints: + * @GDK_HINT_POS: indicates that the program has positioned the window + * @GDK_HINT_MIN_SIZE: min size fields are set + * @GDK_HINT_MAX_SIZE: max size fields are set + * @GDK_HINT_BASE_SIZE: base size fields are set + * @GDK_HINT_ASPECT: aspect ratio fields are set + * @GDK_HINT_RESIZE_INC: resize increment fields are set + * @GDK_HINT_WIN_GRAVITY: window gravity field is set + * @GDK_HINT_USER_POS: indicates that the window's position was explicitly set + * by the user + * @GDK_HINT_USER_SIZE: indicates that the window's size was explicitly set by + * the user + * + * Used to indicate which fields of a #GdkGeometry struct should be paid + * attention to. Also, the presence/absence of @GDK_HINT_POS, + * @GDK_HINT_USER_POS, and @GDK_HINT_USER_SIZE is significant, though they don't + * directly refer to #GdkGeometry fields. @GDK_HINT_USER_POS will be set + * automatically by #GtkWindow if you call gtk_window_move(). + * @GDK_HINT_USER_POS and @GDK_HINT_USER_SIZE should be set if the user + * specified a size/position using a --geometry command-line argument; + * gtk_window_parse_geometry() automatically sets these flags. + */ typedef enum { GDK_HINT_POS = 1 << 0, @@ -118,17 +156,37 @@ typedef enum } GdkWindowHints; -/* Window type hints. - * These are hints for the window manager that indicate - * what type of function the window has. The window manager - * can use this when determining decoration and behaviour - * of the window. The hint must be set before mapping the - * window. +/** + * GdkWindowTypeHint: + * @GDK_WINDOW_TYPE_HINT_NORMAL: Normal toplevel window. + * @GDK_WINDOW_TYPE_HINT_DIALOG: Dialog window. + * @GDK_WINDOW_TYPE_HINT_MENU: Window used to implement a menu; GTK+ uses + * this hint only for torn-off menus, see #GtkTearoffMenuItem. + * @GDK_WINDOW_TYPE_HINT_TOOLBAR: Window used to implement toolbars. + * @GDK_WINDOW_TYPE_HINT_SPLASHSCREEN: Window used to display a splash + * screen during application startup. + * @GDK_WINDOW_TYPE_HINT_UTILITY: Utility windows which are not detached + * toolbars or dialogs. + * @GDK_WINDOW_TYPE_HINT_DOCK: Used for creating dock or panel windows. + * @GDK_WINDOW_TYPE_HINT_DESKTOP: Used for creating the desktop background + * window. + * @GDK_WINDOW_TYPE_HINT_DROPDOWN_MENU: A menu that belongs to a menubar. + * @GDK_WINDOW_TYPE_HINT_POPUP_MENU: A menu that does not belong to a menubar, + * e.g. a context menu. + * @GDK_WINDOW_TYPE_HINT_TOOLTIP: A tooltip. + * @GDK_WINDOW_TYPE_HINT_NOTIFICATION: A notification - typically a "bubble" + * that belongs to a status icon. + * @GDK_WINDOW_TYPE_HINT_COMBO: A popup from a combo box. + * @GDK_WINDOW_TYPE_HINT_DND: A window that is used to implement a DND cursor. + * + * These are hints for the window manager that indicate what type of function + * the window has. The window manager can use this when determining decoration + * and behaviour of the window. The hint must be set before mapping the window. * - * Normal: Normal toplevel window - * Dialog: Dialog window - * Menu: Window used to implement a menu. - * Toolbar: Window used to implement toolbars. + * See the + * Extended + * Window Manager Hints specification for more details about + * window types. */ typedef enum { @@ -153,6 +211,20 @@ typedef enum * of gdk_window_set_decorations/gdk_window_set_functions * will need to change as well. */ +/** + * GdkWMDecoration: + * @GDK_DECOR_ALL: all decorations should be applied. + * @GDK_DECOR_BORDER: a frame should be drawn around the window. + * @GDK_DECOR_RESIZEH: the frame should have resize handles. + * @GDK_DECOR_TITLE: a titlebar should be placed above the window. + * @GDK_DECOR_MENU: a button for opening a menu should be included. + * @GDK_DECOR_MINIMIZE: a minimize button should be included. + * @GDK_DECOR_MAXIMIZE: a maximize button should be included. + * + * These are hints originally defined by the Motif toolkit. + * The window manager can use them when determining how to decorate + * the window. The hint must be set before mapping the window. + */ typedef enum { GDK_DECOR_ALL = 1 << 0, @@ -164,6 +236,19 @@ typedef enum GDK_DECOR_MAXIMIZE = 1 << 6 } GdkWMDecoration; +/** + * GdkWMFunction: + * @GDK_FUNC_ALL: all functions should be offered. + * @GDK_FUNC_RESIZE: the window should be resizable. + * @GDK_FUNC_MOVE: the window should be movable. + * @GDK_FUNC_MINIMIZE: the window should be minimizable. + * @GDK_FUNC_MAXIMIZE: the window should be maximizable. + * @GDK_FUNC_CLOSE: the window should be closable. + * + * These are hints originally defined by the Motif toolkit. The window manager + * can use them when determining the functions to offer for the window. The + * hint must be set before mapping the window. + */ typedef enum { GDK_FUNC_ALL = 1 << 0, @@ -178,6 +263,26 @@ typedef enum * X protocol. If you change that, gdkwindow-x11.c/gdk_window_set_geometry_hints() * will need fixing. */ +/** + * GdkGravity: + * @GDK_GRAVITY_NORTH_WEST: the reference point is at the top left corner. + * @GDK_GRAVITY_NORTH: the reference point is in the middle of the top edge. + * @GDK_GRAVITY_NORTH_EAST: the reference point is at the top right corner. + * @GDK_GRAVITY_WEST: the reference point is at the middle of the left edge. + * @GDK_GRAVITY_CENTER: the reference point is at the center of the window. + * @GDK_GRAVITY_EAST: the reference point is at the middle of the right edge. + * @GDK_GRAVITY_SOUTH_WEST: the reference point is at the lower left corner. + * @GDK_GRAVITY_SOUTH: the reference point is at the middle of the lower edge. + * @GDK_GRAVITY_SOUTH_EAST: the reference point is at the lower right corner. + * @GDK_GRAVITY_STATIC: the reference point is at the top left corner of the + * window itself, ignoring window manager decorations. + * + * Defines the reference point of a window and the meaning of coordinates + * passed to gtk_window_move(). See gtk_window_move() and the "implementation + * notes" section of the + * Extended + * Window Manager Hints specification for more details. + */ typedef enum { GDK_GRAVITY_NORTH_WEST = 1, @@ -193,6 +298,19 @@ typedef enum } GdkGravity; +/** + * GdkWindowEdge: + * @GDK_WINDOW_EDGE_NORTH_WEST: the top left corner. + * @GDK_WINDOW_EDGE_NORTH: the top edge. + * @GDK_WINDOW_EDGE_NORTH_EAST: the top right corner. + * @GDK_WINDOW_EDGE_WEST: the left edge. + * @GDK_WINDOW_EDGE_EAST: the right edge. + * @GDK_WINDOW_EDGE_SOUTH_WEST: the lower left corner. + * @GDK_WINDOW_EDGE_SOUTH: the lower edge. + * @GDK_WINDOW_EDGE_SOUTH_EAST: the lower right corner. + * + * Determines a window edge or corner. + */ typedef enum { GDK_WINDOW_EDGE_NORTH_WEST, @@ -205,6 +323,27 @@ typedef enum GDK_WINDOW_EDGE_SOUTH_EAST } GdkWindowEdge; +/** + * GdkWindowAttr: + * @title: title of the window (for toplevel windows) + * @event_mask: event mask (see gdk_window_set_events()) + * @x: X coordinate relative to parent window (see gdk_window_move()) + * @y: Y coordinate relative to parent window (see gdk_window_move()) + * @width: width of window + * @height: height of window + * @wclass: #GDK_INPUT_OUTPUT (normal window) or #GDK_INPUT_ONLY (invisible + * window that receives events) + * @visual: #GdkVisual for window + * @colormap: #GdkColormap for window + * @window_type: type of window + * @cursor: cursor for the window (see gdk_window_set_cursor()) + * @wmclass_name: don't use (see gtk_window_set_wmclass()) + * @wmclass_class: don't use (see gtk_window_set_wmclass()) + * @override_redirect: %TRUE to bypass the window manager + * @type_hint: a hint of the function of the window + * + * Attributes to use for a newly-created window. + */ struct _GdkWindowAttr { gchar *title; @@ -223,6 +362,82 @@ struct _GdkWindowAttr GdkWindowTypeHint type_hint; }; +/** + * GdkGeometry: + * @min_width: minimum width of window (or -1 to use requisition, with + * #GtkWindow only) + * @min_height: minimum height of window (or -1 to use requisition, with + * #GtkWindow only) + * @max_width: maximum width of window (or -1 to use requisition, with + * #GtkWindow only) + * @max_height: maximum height of window (or -1 to use requisition, with + * #GtkWindow only) + * @base_width: allowed window widths are @base_width + @width_inc * N where N + * is any integer (-1 allowed with #GtkWindow) + * @base_height: allowed window widths are @base_height + @height_inc * N where + * N is any integer (-1 allowed with #GtkWindow) + * @width_inc: width resize increment + * @height_inc: height resize increment + * @min_aspect: minimum width/height ratio + * @max_aspect: maximum width/height ratio + * @win_gravity: window gravity, see gtk_window_set_gravity() + * + * The #GdkGeometry struct gives the window manager information about + * a window's geometry constraints. Normally you would set these on + * the GTK+ level using gtk_window_set_geometry_hints(). #GtkWindow + * then sets the hints on the #GdkWindow it creates. + * + * gdk_window_set_geometry_hints() expects the hints to be fully valid already + * and simply passes them to the window manager; in contrast, + * gtk_window_set_geometry_hints() performs some interpretation. For example, + * #GtkWindow will apply the hints to the geometry widget instead of the + * toplevel window, if you set a geometry widget. Also, the + * @min_width/@min_height/@max_width/@max_height fields may be set to -1, and + * #GtkWindow will substitute the size request of the window or geometry widget. + * If the minimum size hint is not provided, #GtkWindow will use its requisition + * as the minimum size. If the minimum size is provided and a geometry widget is + * set, #GtkWindow will take the minimum size as the minimum size of the + * geometry widget rather than the entire window. The base size is treated + * similarly. + * + * The canonical use-case for gtk_window_set_geometry_hints() is to get a + * terminal widget to resize properly. Here, the terminal text area should be + * the geometry widget; #GtkWindow will then automatically set the base size to + * the size of other widgets in the terminal window, such as the menubar and + * scrollbar. Then, the @width_inc and @height_inc fields should be set to the + * size of one character in the terminal. Finally, the base size should be set + * to the size of one character. The net effect is that the minimum size of the + * terminal will have a 1x1 character terminal area, and only terminal sizes on + * the "character grid" will be allowed. + * + * Here's an example of how the terminal example would be implemented, assuming + * a terminal area widget called "terminal" and a toplevel window "toplevel": + * + * char_width; + * hints.base_height = terminal->char_height; + * hints.min_width = terminal->char_width; + * hints.min_height = terminal->char_height; + * hints.width_inc = terminal->char_width; + * hints.height_inc = terminal->char_height; + * + * gtk_window_set_geometry_hints (GTK_WINDOW (toplevel), + * GTK_WIDGET (terminal), + * &hints, + * GDK_HINT_RESIZE_INC | + * GDK_HINT_MIN_SIZE | + * GDK_HINT_BASE_SIZE); + * ]]> + * + * The other useful fields are the @min_aspect and @max_aspect fields; these + * contain a width/height ratio as a floating point number. If a geometry widget + * is set, the aspect applies to the geometry widget rather than the entire + * window. The most common use of these hints is probably to set @min_aspect and + * @max_aspect to the same value, thus forcing the window to keep a constant + * aspect ratio. + */ struct _GdkGeometry { gint min_width; @@ -238,6 +453,23 @@ struct _GdkGeometry GdkGravity win_gravity; }; +/** + * GdkPointerHooks: + * @get_pointer: Obtains the current pointer position and modifier state. + * The position is given in coordinates relative to the window containing + * the pointer, which is returned in @window. + * @window_at_pointer: Obtains the window underneath the mouse pointer, + * returning the location of that window in @win_x, @win_y. Returns %NULL + * if the window under the mouse pointer is not known to GDK (for example, + * belongs to another application). + * + * A table of pointers to functions for getting quantities related to + * the current pointer position. GDK has one global table of this type, + * which can be set using gdk_set_pointer_hooks(). + * + * This is only useful for such low-level tools as an event recorder. + * Applications should never have any reason to use this facility + */ struct _GdkPointerHooks { GdkWindow* (*get_pointer) (GdkWindow *window, diff --git a/gdk/x11/gdkdnd-x11.c b/gdk/x11/gdkdnd-x11.c index 631dbed477..8f6730078d 100644 --- a/gdk/x11/gdkdnd-x11.c +++ b/gdk/x11/gdkdnd-x11.c @@ -3837,6 +3837,12 @@ gdk_drop_finish (GdkDragContext *context, } +/** + * gdk_window_register_dnd: + * @window: a #GdkWindow. + * + * Registers a window as a potential drop destination. + */ void gdk_window_register_dnd (GdkWindow *window) { diff --git a/gdk/x11/gdkwindow-x11.c b/gdk/x11/gdkwindow-x11.c index 2dc074af7d..92a64fb47b 100644 --- a/gdk/x11/gdkwindow-x11.c +++ b/gdk/x11/gdkwindow-x11.c @@ -4456,8 +4456,10 @@ gdk_window_set_decorations (GdkWindow *window, * @window: The toplevel #GdkWindow to get the decorations from * @decorations: The window decorations will be written here * - * Returns the decorations set on the GdkWindow with #gdk_window_set_decorations - * Returns: TRUE if the window has decorations set, FALSE otherwise. + * Returns the decorations set on the GdkWindow with + * gdk_window_set_decorations(). + * + * Returns: %TRUE if the window has decorations set, %FALSE otherwise. **/ gboolean gdk_window_get_decorations(GdkWindow *window, -- 2.30.2